Cream of the Crop 26/Cream of the Crop 26.iso/os2/octa209b.zip/octave-2.09/doc/octave.i02

GNU Info File | 1997-08-20 | 49KB | 1,014 lines

This is Info file octave, produced by Makeinfo-1.64 from the input file
octave.tex.
START-INFO-DIR-ENTRY
* Octave: (octave).     Interactive language for numerical computations.
END-INFO-DIR-ENTRY
   Copyright (C) 1996, 1997 John W. Eaton.
   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.
File: octave,  Node: Commands For Text,  Next: Commands For Completion,  Prev: Killing and Yanking,  Up: Command Line Editing
Commands For Changing Text
--------------------------
   The following commands can be used for entering characters that would
otherwise have a special meaning (e.g., `TAB', `C-q', etc.), or for
quickly correcting typing mistakes.
`C-q'
`C-v'
     Add the next character that you type to the line verbatim.  This is
     how to insert things like `C-q' for example.
`M-TAB'
     Insert a tab character.
`C-t'
     Drag the character before the cursor forward over the character at
     the cursor, also moving the cursor forward.  If the cursor is at
     the end of the line, then transpose the two characters before it.
`M-t'
     Drag the word behind the cursor past the word in front of the
     cursor moving the cursor over that word as well.
`M-u'
     Uppercase the characters following the cursor to the end of the
     current (or following) word, moving the cursor to the end of the
     word.
`M-l'
     Lowecase the characters following the cursor to the end of the
     current (or following) word, moving the cursor to the end of the
     word.
`M-c'
     Uppercase the character following the cursor (or the beginning of
     the next word if the cursor is between words), moving the cursor
     to the end of the word.
File: octave,  Node: Commands For Completion,  Next: Commands For History,  Prev: Commands For Text,  Up: Command Line Editing
Letting Readline Type For You
-----------------------------
   The following commands allow Octave to complete command and variable
names for you.
`TAB'
     Attempt to do completion on the text before the cursor.  Octave can
     complete the names of commands and variables.
`M-?'
     List the possible completions of the text before the cursor.
 - Built-in Variable: completion_append_char
     The value of `completion_append_char' is used as the character to
     append to successful command-line completion attempts.  The default
     value is `" "' (a single space).
 - Built-in Function:  completion_matches (HINT)
     Generate possible completions given HINT.
     This function is provided for the benefit of programs like Emacs
     which might be controlling Octave and handling user input.  The
     current command number is not incremented when this function is
     called.  This is a feature, not a bug.
File: octave,  Node: Commands For History,  Next: Customizing the Prompt,  Prev: Commands For Completion,  Up: Command Line Editing
Commands For Manipulating The History
-------------------------------------
   Octave normally keeps track of the commands you type so that you can
recall previous commands to edit or execute them again.  When you exit
Octave, the most recent commands you have typed, up to the number
specified by the variable `history_size', are saved in a file.  When
Octave starts, it loads an initial list of commands from the file named
by the variable `history_file'.
   Here are the commands for simple browsing and searching the history
list.
`LFD'
`RET'
     Accept the line regardless of where the cursor is.  If this line is
     non-empty, add it to the history list.  If this line was a history
     line, then restore the history line to its original state.
`C-p'
     Move `up' through the history list.
`C-n'
     Move `down' through the history list.
`M-<'
     Move to the first line in the history.
`M->'
     Move to the end of the input history, i.e., the line you are
     entering!
`C-r'
     Search backward starting at the current line and moving `up'
     through the history as necessary.  This is an incremental search.
`C-s'
     Search forward starting at the current line and moving `down'
     through the the history as necessary.
   On most terminals, you can also use the arrow keys in place of `C-p'
and `C-n' to move through the history list.
   In addition to the keyboard commands for moving through the history
list, Octave provides three functions for viewing, editing, and
re-running chunks of commands from the history list.
 - Command: history OPTIONS
     If invoked with no arguments, `history' displays a list of commands
     that you have executed.  Valid options are:
    `-w FILE'
          Write the current history to the file FILE.  If the name is
          omitted, use the default history file (normally
          `~/.octave_hist').
    `-r FILE'
          Read the file FILE, replacing the current history list with
          its contents.  If the name is omitted, use the default
          history file (normally `~/.octave_hist').
    `N'
          Only display the most recent N lines of history.
    `-q'
          Don't number the displayed lines of history.  This is useful
          for cutting and pasting commands if you are using the X
          Window System.
     For example, to display the five most recent commands that you have
     typed without displaying line numbers, use the command `history -q
     5'.
 - Command: edit_history OPTIONS
     If invoked with no arguments, `edit_history' allows you to edit the
     history list using the editor named by the variable `EDITOR'.  The
     commands to be edited are first copied to a temporary file.  When
     you exit the editor, Octave executes the commands that remain in
     the file.  It is often more convenient to use `edit_history' to
     define functions rather than attempting to enter them directly on
     the command line.  By default, the block of commands is executed
     as soon as you exit the editor.  To avoid executing any commands,
     simply delete all the lines from the buffer before exiting the
     editor.
     The `edit_history' command takes two optional arguments specifying
     the history numbers of first and last commands to edit.  For
     example, the command
          edit_history 13
     extracts all the commands from the 13th through the last in the
     history list.  The command
          edit_history 13 169
     only extracts commands 13 through 169.  Specifying a larger number
     for the first command than the last command reverses the list of
     commands before placing them in the buffer to be edited.  If both
     arguments are omitted, the previous command in the history list is
     used.
 - Command: run_history
     Similar to `edit_history', except that the editor is not invoked,
     and the commands are simply executed as they appear in the history
     list.
 - Built-in Variable: EDITOR
     A string naming the editor to use with the `edit_history' command.
     If the environment variable `EDITOR' is set when Octave starts, its
     value is used as the default.  Otherwise, `EDITOR' is set to
     `"emacs"'.
 - Built-in Variable: history_file
     This variable specifies the name of the file used to store command
     history.  The default value is `"~/.octave_hist"', but may be
     overridden by the environment variable `OCTAVE_HISTFILE'.
 - Built-in Variable: history_size
     This variable specifies how many entries to store in the history
     file.  The default value is `1024', but may be overridden by the
     environment variable `OCTAVE_HISTSIZE'.
 - Built-in Variable: saving_history
     If the value of `saving_history' is `"true"', command entered on
     the command line are saved in the file specified by the variable
     `history_file'.
File: octave,  Node: Customizing the Prompt,  Next: Diary and Echo Commands,  Prev: Commands For History,  Up: Command Line Editing
Customizing the Prompt
----------------------
   The following variables are available for customizing the appearance
of the command-line prompts.  Octave allows the prompt to be customized
by inserting a number of backslash-escaped special characters that are
decoded as follows:
     The time.
     The date.
     Begins a new line by printing the equivalent of a carriage return
     followed by a line feed.
     The name of the program (usually just `octave').
     The current working directory.
     The basename of the current working directory.
     The username of the current user.
     The hostname, up to the first `.'.
     The hostname.
     The command number of this command, counting from when Octave
     starts.
     The history number of this command.  This differs from `\#' by the
     number of commands in the history list when Octave starts.
     If the effective UID is 0, a `#', otherwise a `$'.
`\nnn'
     The character whose character code in octal is NNN.
     A backslash.
 - Built-in Variable: PS1
     The primary prompt string.  When executing interactively, Octave
     displays the primary prompt `PS1' when it is ready to read a
     command.
     The default value of `PS1' is `"\s:\#> "'.  To change it, use a
     command like
          octave:13> PS1 = "\\u@\\H> "
     which will result in the prompt `boris@kremvax> ' for the user
     `boris' logged in on the host `kremvax.kgb.su'.  Note that two
     backslashes are required to enter a backslash into a string.
     *Note Strings::.
 - Built-in Variable: PS2
     The secondary prompt string, which is printed when Octave is
     expecting additional input to complete a command.  For example,
     when defining a function over several lines, Octave will print the
     value of `PS1' at the beginning of each line after the first.  The
     default value of `PS2' is `"> "'.
 - Built-in Variable: PS4
     If Octave is invoked with the `--echo-input' option, the value of
     `PS4' is printed before each line of input that is echoed.  The
     default value of `PS4' is `"+ "'.  *Note Invoking Octave::, for a
     description of `--echo-input'.
File: octave,  Node: Diary and Echo Commands,  Prev: Customizing the Prompt,  Up: Command Line Editing
Diary and Echo Commands
-----------------------
   Octave's diary feature allows you to keep a log of all or part of an
interactive session by recording the input you type and the output that
Octave produces in a separate file.
 - Command: diary OPTIONS
     Create a list of all commands *and* the output they produce, mixed
     together just as you see them on your terminal.  Valid options are:
    `on'
          Start recording your session in a file called `diary' in your
          current working directory.
    `off'
          Stop recording your session in the diary file.
    `FILE'
          Record your session in the file named FILE.
     Without any arguments, `diary' toggles the current diary state.
   Sometimes it is useful to see the commands in a function or script as
they are being evaluated.  This can be especially helpful for debugging
some kinds of problems.
 - Command: echo OPTIONS
     Control whether commands are displayed as they are executed.  Valid
     options are:
    `on'
          Enable echoing of commands as they are executed in script
          files.
    `off'
          Disable echoing of commands as they are executed in script
          files.
    `on all'
          Enable echoing of commands as they are executed in script
          files and functions.
    `off all'
          Disable echoing of commands as they are executed in script
          files and functions.
     If invoked without any arguments, `echo' toggles the current echo
     state.
 - Built-in Variable: echo_executing_commands
     This variable is may also be used to control the echo state.  It
     may be the sum of the following values:
    1
          Echo commands read from script files.
    2
          Echo commands from functions.
    4
          Echo commands read from command line.
     More than one state can be active at once.  For example, a value
     of 3 is equivalent to the command `echo on all'.
     The value of `echo_executing_commands' is set by the `echo'
     command and the command line option `--echo-input'.
File: octave,  Node: Errors,  Next: Executable Octave Programs,  Prev: Command Line Editing,  Up: Getting Started
How Octave Reports Errors
=========================
   Octave reports two kinds of errors for invalid programs.
   A "parse error" occurs if Octave cannot understand something you
have typed.  For example, if you misspell a keyword,
     octave:13> functon y = f (x) y = x^2; endfunction
Octave will respond immediately with a message like this:
     parse error:

       functon y = f (x) y = x^2; endfunction
               ^
For most parse errors, Octave uses a caret (`^') to mark the point on
the line where it was unable to make sense of your input.  In this
case, Octave generated an error message because the keyword `function'
was misspelled.  Instead of seeing `function f', Octave saw two
consecutive variable names, which is invalid in this context.  It
marked the error at the `y' because the first name by itself was
accepted as valid input.
   Another class of error message occurs occurs at evaluation time.
These errors are called "run-time errors", or sometimes "evaluation
errors" because they occur when your program is being "run", or
"evaluated".  For example, if after correcting the mistake in the
previous function definition, you type
     octave:13> f ()
Octave will respond with
     error: `x' undefined near line 1 column 24
     error: evaluating expression near line 1, column 24
     error: evaluating assignment expression near line 1, column 22
     error: called from `f'
   This error message has several parts, and gives you quite a bit of
information to help you locate the source of the error.  The messages
are generated from the point of the innermost error, and provide a
traceback of enclosing expressions and function calls.
   In the example above, the first line indicates that a variable named
`x' was found to be undefined near line 1 and column 24 of some
function or expression.  For errors occurring within functions, lines
from the beginning of the file containing the function definition.  For
errors occurring at the top level, the line number indicates the input
line number, which is usually displayed in the prompt string.
   The second and third lines in the example indicate that the error
occurred within an assignment expression, and the last line of the error
message indicates that the error occurred within the function `f'.  If
the function `f' had been called from another function, for example,
`g', the list of errors would have ended with one more line:
     error: called from `g'
   These lists of function calls usually make it fairly easy to trace
the path your program took before the error occurred, and to correct the
error before trying again.
File: octave,  Node: Executable Octave Programs,  Next: Comments,  Prev: Errors,  Up: Getting Started
Executable Octave Programs
==========================
   Once you have learned Octave, you may want to write self-contained
Octave scripts, using the `#!' script mechanism.  You can do this on
GNU systems and on many Unix systems (1)
   For example, you could create a text file named `hello', containing
the following lines:
     #! OCTAVE-INTERPRETER-NAME -qf
     # a sample Octave program
     printf ("Hello, world!\n");
(where OCTAVE-INTERPRETER-NAME should be replaced with the full file
name for your Octave binary).  After making this file executable (with
the `chmod' command), you can simply type:
     hello
at the shell, and the system will arrange to run Octave as if you had
typed:
     octave hello
   The line beginning with `#!' lists the full file name of an
interpreter to be run, and an optional initial command line argument to
pass to that interpreter.  The operating system then runs the
interpreter with the given argument and the full argument list of the
executed program.  The first argument in the list is the full file name
of the Octave program. The rest of the argument list will either be
options to Octave, or data files, or both.  The `-qf' option is usually
specified in stand-alone Octave programs to prevent them from printing
the normal startup message, and to keep them from behaving differently
depending on the contents of a particular user's `~/.octaverc' file.
*Note Invoking Octave::.  Note that some operating systems may place a
limit on the number of characters that are recognized after `#!'.
   Self-contained Octave scripts are useful when you want to write a
program which users can invoke without knowing that the program is
written in the Octave language.
   If you invoke an executable Octave script with command line
arguments, the arguments are available in the built-in variable `argv'.
*Note Command Line Options::.  For example, the following program will
reproduce the command line that is used to execute it.
     #! /bin/octave -qf
     printf ("%s", program_name);
     for i = 1:nargin
       printf (" %s", argv(i,:));
     endfor
     printf ("\n");
   ---------- Footnotes ----------
   (1)  The `#!' mechanism works on Unix systems derived from Berkeley
Unix, System V Release 4, and some System V Release 3 systems.
File: octave,  Node: Comments,  Prev: Executable Octave Programs,  Up: Getting Started
Comments in Octave Programs
===========================
   A "comment" is some text that is included in a program for the sake
of human readers, and that is not really part of the program.  Comments
can explain what the program does, and how it works.  Nearly all
programming languages have provisions for comments, because programs are
typically hard to understand without them.
   In the Octave language, a comment starts with either the sharp sign
character, `#', or the percent symbol `%' and continues to the end of
the line.  The Octave interpreter ignores the rest of a line following
a sharp sign or percent symbol.  For example, we could have put the
following into the function `f':
     function xdot = f (x, t)

     # usage: f (x, t)
     #
     # This function defines the right hand
     # side functions for a set of nonlinear
     # differential equations.

       r = 0.25;
       ...
     endfunction
   The `help' command (*note Getting Help::.) is able to find the first
block of comments in a function (even those that are composed directly
on the command line).  This means that users of Octave can use the same
commands to get help for built-in functions, and for functions that you
have defined.  For example, after defining the function `f' above, the
command `help f' produces the output
      usage: f (x, t)

      This function defines the right hand
      side functions for a set of nonlinear
      differential equations.
   Although it is possible to put comment lines into keyboard-composed
throw-away Octave programs, it usually isn't very useful, because the
purpose of a comment is to help you or another person understand the
program at a later time.
File: octave,  Node: Data Types,  Next: Numeric Data Types,  Prev: Getting Started,  Up: Top
Data Types
**********
   All versions of Octave include a number of built-in data types,
including real and complex scalars and matrices, character strings, and
a data structure type.
   It is also possible to define new specialized data types by writing a
small amount of C++ code.  On some systems, new data types can be loaded
dynamically while Octave is running, so it is not necessary to recompile
all of Octave just to add a new type.  *Note Dynamically Linked
Functions:: for more information about Octave's dynamic linking
capabilities.  *Note User-defined Data Types:: describes what you must
do to define a new data type for Octave.
* Menu:
* Built-in Data Types::
* User-defined Data Types::
* Object Sizes::
File: octave,  Node: Built-in Data Types,  Next: User-defined Data Types,  Prev: Data Types,  Up: Data Types
Built-in Data Types
===================
   The standard built-in data types are real and complex scalars and
matrices, ranges, character strings, and a data structure type.
Additional built-in data types may be added in future versions.  If you
need a specialized data type that is not currently provided as a
built-in type, you are encouraged to write your own user-defined data
type and contribute it for distribution in a future release of Octave.
* Menu:
* Numeric Objects::
* String Objects::
* Data Structure Objects::
File: octave,  Node: Numeric Objects,  Next: String Objects,  Prev: Built-in Data Types,  Up: Built-in Data Types
Numeric Objects
---------------
   Octave's built-in numeric objects include real and complex scalars
and matrices.  All built-in numeric data is currently stored as double
precision numbers.  On systems that use the IEEE floating point format,
values in the range of approximately  2.2251e-308 to 1.7977e+308  can
be stored, and the relative precision is approximately  2.2204e-16.
The exact values are given by the variables `realmin', `realmax', and
`eps', respectively.
   Matrix objects can be of any size, and can be dynamically reshaped
and resized.  It is easy to extract individual rows, columns, or
submatrices is using a variety of powerful indexing features.  *Note
Index Expressions::.
   *Note Numeric Data Types::, for more information.
File: octave,  Node: String Objects,  Next: Data Structure Objects,  Prev: Numeric Objects,  Up: Built-in Data Types
String Objects
--------------
   A character string in Octave consists of a sequence of characters
enclosed in either double-quote or single-quote marks.  Internally,
Octave currently stores strings as matrices of characters.  All the
indexing operations that work for matrix objects also work for strings.
   *Note Strings::, for more information.
File: octave,  Node: Data Structure Objects,  Prev: String Objects,  Up: Built-in Data Types
Data Structure Objects
----------------------
   Octave's data structure type can help you to organize related
objects of different types.  The current implementation uses an
associative array with indices limited to strings, but the syntax is
more like C-style structures.
   *Note Data Structures::, for more information.
File: octave,  Node: User-defined Data Types,  Next: Object Sizes,  Prev: Built-in Data Types,  Up: Data Types
User-defined Data Types
=======================
   Someday I hope to expand this to include a complete description of
Octave's mechanism for managing user-defined data types.  Until this
feature is documented here, you will have to make do by reading the code
in the `ov.h', `ops.h', and related files from Octave's `src' directory.
File: octave,  Node: Object Sizes,  Prev: User-defined Data Types,  Up: Data Types
Object Sizes
============
   The following functions allow you to determine the size of a
variable or expression.  These functions are defined for all objects.
They return -1 when the operation doesn't make sense.  For example,
Octave's data structure type doesn't have rows or columns, so the
`rows' and `columns' functions return -1 for structure arguments.
 - Function File:  columns (A)
     Return the number of columns of A.
 - Function File:  rows (A)
     Return the number of rows of A.
 - Function File:  length (A)
     Return the number of rows of A or the number of columns of A,
     whichever is larger.
 - Function File:  size (A, N)
     Return the number rows and columns of A.
     With one input argument and one output argument, the result is
     returned in a 2 element row vector.  If there are two output
     arguments, the number of rows is assigned to the first, and the
     number of columns to the second.  For example,
          size ([1, 2; 3, 4; 5, 6])
               => [ 3, 2 ]

          [nr, nc] = size ([1, 2; 3, 4; 5, 6])
               => nr = 3
               => nc = 2
     If given a second argument of either 1 or 2, `size' will return
     only the row or column dimension.  For example
          size ([1, 2; 3, 4; 5, 6], 2)
               => 2
     returns the number of columns in the given matrix.
 - Function File:  isempty (A)
     Return 1 if A is an empty matrix (either the number of rows, or
     the number of columns, or both are zero).  Otherwise, return 0.
File: octave,  Node: Numeric Data Types,  Next: Strings,  Prev: Data Types,  Up: Top
Numeric Data Types
******************
   A "numeric constant" may be a scalar, a vector, or a matrix, and it
may contain complex values.
   The simplest form of a numeric constant, a scalar, is a single number
that can be an integer, a decimal fraction, a number in scientific
(exponential) notation, or a complex number.  Note that all numeric
constants are represented within Octave in double-precision floating
point format (complex constants are stored as pairs of double-precision
floating point values).  Here are some examples of real-valued numeric
constants, which all have the same value:
     105
     1.05e+2
     1050e-1
   To specify complex constants, you can write an expression of the form
     3 + 4i
     3.0 + 4.0i
     0.3e1 + 40e-1i
   all of which are equivalent.  The letter `i' in the previous example
stands for the pure imaginary constant, defined as   `sqrt (-1)'.
   For Octave to recognize a value as the imaginary part of a complex
constant, a space must not appear between the number and the `i'.  If
it does, Octave will print an error message, like this:
     octave:13> 3 + 4 i

     parse error:

       3 + 4 i
             ^
   You may also use `j', `I', or `J' in place of the `i' above.  All
four forms are equivalent.
* Menu:
* Matrices::
* Ranges::
* Predicates for Numeric Objects::
File: octave,  Node: Matrices,  Next: Ranges,  Prev: Numeric Data Types,  Up: Numeric Data Types
Matrices
========
   It is easy to define a matrix of values in Octave.  The size of the
matrix is determined automatically, so it is not necessary to explicitly
state the dimensions.  The expression
     a = [1, 2; 3, 4]
results in the matrix
             /      \
             | 1  2 |
       a  =  |      |
             | 3  4 |
             \      /
   Elements of a matrix may be arbitrary expressions, provided that the
dimensions all make sense when combining the various pieces.  For
example, given the above matrix, the expression
     [ a, a ]
produces the matrix
     ans =

       1  2  1  2
       3  4  3  4
but the expression
     [ a, 1 ]
produces the error
     error: number of rows must match near line 13, column 6
(assuming that this expression was entered as the first thing on line
13, of course).
   Inside the square brackets that delimit a matrix expression, Octave
looks at the surrounding context to determine whether spaces and newline
characters should be converted into element and row separators, or
simply ignored, so commands like
     [ linspace (1, 2) ]
     a = [ 1 2
           3 4 ]
will work.  However, some possible sources of confusion remain.  For
example, in the expression
     [ 1 - 1 ]
the `-' is treated as a binary operator and the result is the scalar 0,
but in the expression
     [ 1 -1 ]
the `-' is treated as a unary operator and the result is the vector `[
1, -1 ]'.
   Given `a = 1', the expression
     [ 1 a' ]
results in the single quote character `'' being treated as a transpose
operator and the result is the vector `[ 1, 1 ]', but the expression
     [ 1 a ' ]
produces the error message
     error: unterminated string constant
because to not do so would make it impossible to correctly parse the
valid expression
     [ a 'foo' ]
   For clarity, it is probably best to always use commas and semicolons
to separate matrix elements and rows.  It is possible to enforce this
style by setting the built-in variable `whitespace_in_literal_matrix' to
`"ignore"'.
 - Built-in Variable: whitespace_in_literal_matrix
     This variable allows some control over how Octave decides to
     convert spaces to commas and semicolons in matrix expressions like
     `[m (1)]' or
          [ 1, 2,
            3, 4 ]
     If the value of `whitespace_in_literal_matrix' is `"ignore"',
     Octave will never insert a comma or a semicolon in a literal matrix
     list.  For example, the expression `[1 2]' will result in an error
     instead of being treated the same as `[1, 2]', and the expression
          [ 1, 2,
            3, 4 ]
     will result in the vector `[ 1, 2, 3, 4 ]' instead of a matrix.
     If the value of `whitespace_in_literal_matrix' is `"traditional"',
     Octave will convert spaces to a comma between identifiers and `('.
     For example, given the matrix
          m = [3 2]
     the expression
          [m (1)]
     will be parsed as
          [m, (1)]
     and will result in
          [3 2 1]
     and the expression
          [ 1, 2,
            3, 4 ]
     will result in a matrix because the newline character is converted
     to a semicolon (row separator) even though there is a comma at the
     end of the first line (trailing commas or semicolons are ignored).
     This is apparently how MATLAB behaves.
     Any other value for `whitespace_in_literal_matrix' results in
     behavior that is the same as traditional, except that Octave does
     not convert spaces to a comma between identifiers and `('.  For
     example, the expression
          [m (1)]
     will produce `3'.  This is the way Octave has always behaved.
   When you type a matrix or the name of a variable whose value is a
matrix, Octave responds by printing the matrix in with neatly aligned
rows and columns.  If the rows of the matrix are too large to fit on the
screen, Octave splits the matrix and displays a header before each
section to indicate which columns are being displayed.
You can use the following variables to control the format of the output.
 - Built-in Variable: output_max_field_width
     This variable specifies the maximum width of a numeric output
     field.  The default value is 10.
 - Built-in Variable: output_precision
     This variable specifies the minimum number of significant figures
     to display for numeric output.  The default value is 5.
   It is possible to achieve a wide range of output styles by using
different values of `output_precision' and `output_max_field_width'.
Reasonable combinations can be set using the `format' function.  *Note
Basic Input and Output::.
 - Built-in Variable: split_long_rows
     For large matrices, Octave may not be able to display all the
     columns of a given row on one line of your screen.  This can
     result in missing information or output that is nearly impossible
     to decipher, depending on whether your terminal truncates or wraps
     long lines.
     If the value of `split_long_rows' is nonzero, Octave will display
     the matrix in a series of smaller pieces, each of which can fit
     within the limits of your terminal width.  Each set of rows is
     labeled so that you can easily see which columns are currently
     being displayed.  For example:
          octave:13> rand (2,10)
          ans =

           Columns 1 through 6:

            0.75883  0.93290  0.40064  0.43818  0.94958  0.16467
            0.75697  0.51942  0.40031  0.61784  0.92309  0.40201

           Columns 7 through 10:

            0.90174  0.11854  0.72313  0.73326
            0.44672  0.94303  0.56564  0.82150
     The default value of `split_long_rows' is nonzero.
* Menu:
* Empty Matrices::
File: octave,  Node: Empty Matrices,  Prev: Matrices,  Up: Matrices
Empty Matrices
--------------
   A matrix may have one or both dimensions zero, and operations on
empty matrices are handled as described by Carl de Boor in `An Empty
Exercise', SIGNUM, Volume 25, pages 2-6, 1990 and C. N. Nett and W. M.
Haddad, in `A System-Theoretic Appropriate Realization of the Empty
Matrix Concept', IEEE Transactions on Automatic Control, Volume 38,
Number 5, May 1993.  Briefly, given a scalar S, an M by N matrix
`M(mxn)', and an M by N empty matrix `[](mxn)' (with either one or both
dimensions equal to zero), the following are true:
     s * [](mxn) = [](mxn) * s = [](mxn)

         [](mxn) + [](mxn) = [](mxn)

         [](0xm) *  M(mxn) = [](0xn)

          M(mxn) * [](nx0) = [](mx0)

         [](mx0) * [](0xn) =  0(mxn)
   By default, dimensions of the empty matrix are printed along with the
empty matrix symbol, `[]'.  The built-in variable
`print_empty_dimensions' controls this behavior.
 - Built-in Variable: print_empty_dimensions
     If the value of `print_empty_dimensions' is nonzero, the
     dimensions of empty matrices are printed along with the empty
     matrix symbol, `[]'.  For example, the expression
          zeros (3, 0)
     will print
          ans = [](3x0)
   Empty matrices may also be used in assignment statements as a
convenient way to delete rows or columns of matrices.  *Note Assignment
Expressions: Assignment Ops.
   Octave will normally issue a warning if it finds an empty matrix in
the list of elements that make up another matrix.  You can use the
variable `empty_list_elements_ok' to suppress the warning or to treat
it as an error.
 - Built-in Variable: empty_list_elements_ok
     This variable controls whether Octave ignores empty matrices in a
     matrix list.
     For example, if the value of `empty_list_elements_ok' is nonzero,
     Octave will ignore the empty matrices in the expression
          a = [1, [], 3, [], 5]
     and the variable `a' will be assigned the value `[ 1, 3, 5 ]'.
     The default value is `"warn"'.
   When Octave parses a matrix expression, it examines the elements of
the list to determine whether they are all constants.  If they are, it
replaces the list with a single matrix constant.
 - Built-in Variable: propagate_empty_matrices
     If the value of `propagate_empty_matrices' is nonzero, functions
     like `inverse' and `svd' will return an empty matrix if they are
     given one as an argument.  The default value is 1.
File: octave,  Node: Ranges,  Next: Predicates for Numeric Objects,  Prev: Matrices,  Up: Numeric Data Types
Ranges
======
   A "range" is a convenient way to write a row vector with evenly
spaced elements.  A range expression is defined by the value of the
first element in the range, an optional value for the increment between
elements, and a maximum value which the elements of the range will not
exceed.  The base, increment, and limit are separated by colons (the
`:' character) and may contain any arithmetic expressions and function
calls.  If the increment is omitted, it is assumed to be 1.  For
example, the range
     1 : 5
defines the set of values `[ 1, 2, 3, 4, 5 ]', and the range
     1 : 3 : 5
defines the set of values `[ 1, 4 ]'.
   Although a range constant specifies a row vector, Octave does *not*
convert range constants to vectors unless it is necessary to do so.
This allows you to write a constant like `1 : 10000' without using
80,000 bytes of storage on a typical 32-bit workstation.
   Note that the upper (or lower, if the increment is negative) bound on
the range is not always included in the set of values, and that ranges
defined by floating point values can produce surprising results because
Octave uses floating point arithmetic to compute the values in the
range.  If it is important to include the endpoints of a range and the
number of elements is known, you should use the `linspace' function
instead (*note Special Utility Matrices::.).
   When Octave parses a range expression, it examines the elements of
the expression to determine whether they are all constants.  If they
are, it replaces the range expression with a single range constant.
File: octave,  Node: Predicates for Numeric Objects,  Prev: Ranges,  Up: Numeric Data Types
Predicates for Numeric Objects
==============================
 - Function File:  is_matrix (A)
     Return 1 if A is a matrix.  Otherwise, return 0.
 - Function File:  is_vector (A)
     Return 1 if A is a vector.  Otherwise, return 0.
 - Function File:  is_scalar (A)
     Return 1 if A is a scalar.  Otherwise, return 0.
 - Function File:  is_square (X)
     If X is a square matrix, then return the dimension of X.
     Otherwise, return 0.
 - Function File:  is_symmetric (X, TOL)
     If X is symmetric within the tolerance specified by TOL, then
     return the dimension of X.  Otherwise, return 0.  If TOL is
     omitted, use a tolerance equal to the machine precision.
File: octave,  Node: Strings,  Next: Data Structures,  Prev: Numeric Data Types,  Up: Top
Strings
*******
   A "string constant" consists of a sequence of characters enclosed in
either double-quote or single-quote marks.  For example, both of the
following expressions
     "parrot"
     'parrot'
represent the string whose contents are `parrot'.  Strings in Octave
can be of any length.
   Since the single-quote mark is also used for the transpose operator
(*note Arithmetic Ops::.) but double-quote marks have no other purpose
in Octave, it is best to use double-quote marks to denote strings.
   Some characters cannot be included literally in a string constant.
You represent them instead with "escape sequences", which are character
sequences beginning with a backslash (`\').
   One use of an escape sequence is to include a double-quote
(single-quote) character in a string constant that has been defined
using double-quote (single-quote) marks.  Since a plain double-quote
would end the string, you must use `\"' to represent a single
double-quote character as a part of the string.  The backslash character
itself is another character that cannot be included normally.  You must
write `\\' to put one backslash in the string.  Thus, the string whose
contents are the two characters `"\' may be written `"\"\\"' or
`'"\\''.  Similarly, the string whose contents are the two characters
`'\' may be written `'\'\\'' or `"'\\"'.
   Another use of backslash is to represent unprintable characters such
as newline.  While there is nothing to stop you from writing most of
these characters directly in a string constant, they may look ugly.
   Here is a table of all the escape sequences used in Octave.  They are
the same as those used in the C programming language.
     Represents a literal backslash, `\'.
     Represents a literal double-quote character, `"'.
     Represents a literal single-quote character, `''.
     Represents the "alert" character, control-g, ASCII code 7.
     Represents a backspace, control-h, ASCII code 8.
     Represents a formfeed, control-l, ASCII code 12.
     Represents a newline, control-j, ASCII code 10.
     Represents a carriage return, control-m, ASCII code 13.
     Represents a horizontal tab, control-i, ASCII code 9.
     Represents a vertical tab, control-k, ASCII code 11.
   Strings may be concatenated using the notation for defining matrices.
For example, the expression
     [ "foo" , "bar" , "baz" ]
produces the string whose contents are `foobarbaz'.  *Note Numeric Data
Types:: for more information about creating matrices.
* Menu:
* Creating Strings::
* Searching and Replacing::
* String Conversions::
* Character Class Functions::
File: octave,  Node: Creating Strings,  Next: Searching and Replacing,  Prev: Strings,  Up: Strings
Creating Strings
================
 - Function File:  blanks (N)
     Return a string of N blanks.
 - Function File:  int2str (N)
 - Function File:  num2str (X)
     Convert a number to a string.  These functions are not very
     flexible, but are provided for compatibility with MATLAB.  For
     better control over the results, use `sprintf' (*note Formatted
     Output::.).
 - Built-in Function:  setstr (X)
     Convert a matrix to a string.  Each element of the matrix is
     converted to the corresponding ASCII character.  For example,
          setstr ([97, 98, 99])
               => "abc"
 - Function File:  strcat (S1, S2, ...)
     Return a string containing all the arguments concatenated.  For
     example,
          s = [ "ab"; "cde" ];
          strcat (s, s, s)
               => "ab ab ab "
                  "cdecdecde"
 - Built-in Variable: string_fill_char
     The value of this variable is used to pad all strings in a string
     matrix to the same length.  It should be a single character.  The
     default value is `" "' (a single space).  For example,
          string_fill_char = "X";
          [ "these"; "are"; "strings" ]
               => "theseXX"
                  "areXXXX"
                  "strings"
 - Function File:  str2mat (S_1, ..., S_N)
     Return a matrix containing the strings S_1, ..., S_N as its rows.
     Each string is padded with blanks in order to form a valid matrix.
     *Note:* This function is modelled after MATLAB.  In Octave, you
     can create a matrix of strings by `[S_1; ...; S_N]' even if the
     strings are not all the same length.
 - Built-in Function:  isstr (A)
     Return 1 if A is a string.  Otherwise, return 0.
File: octave,  Node: Searching and Replacing,  Next: String Conversions,  Prev: Creating Strings,  Up: Strings
Searching and Replacing
=======================
 - Function File:  deblank (S)
     Removes the trailing blanks from the string S.
 - Function File:  findstr (S, T, OVERLAP)
     Return the vector of all positions in the longer of the two strings
     S and T where an occurrence of the shorter of the two starts.  If
     the optional argument OVERLAP is nonzero, the returned vector can
     include overlapping positions (this is the default).  For example,
          findstr ("ababab", "a")
               => [ 1, 3, 5 ]
          findstr ("abababa", "aba", 0)
               => [ 1, 5 ]
 - Function File:  index (S, T)
     Return the position of the first occurrence of the string T in the
     string S, or 0 if no occurrence is found.  For example,
          index ("Teststring", "t")
               => 4
     *Note:*  This function does not work for arrays of strings.
 - Function File:  rindex (S, T)
     Return the position of the last occurrence of the string T in the
     string S, or 0 if no occurrence is found.  For example,
          rindex ("Teststring", "t")
               => 6
     *Note:*  This function does not work for arrays of strings.
 - Function File:  split (S, T)
     Divides the string S into pieces separated by T, returning the
     result in a string array (padded with blanks to form a valid
     matrix).  For example,
          split ("Test string", "t")
               => "Tes "
                  " s  "
                  "ring"
 - Function File:  strcmp (S1, S2)
     Compares two strings, returning 1 if they are the same, and 0
     otherwise.
     *Note:*  For compatibility with MATLAB, Octave's strcmp function
     returns 1 if the strings are equal, and 0 otherwise.  This is just
     the opposite of the corresponding C library function.
 - Function File:  strrep (S, X, Y)
     Replaces all occurrences of the substring X of the string S with
     the string Y.  For example,
          strrep ("This is a test string", "is", "&%$")
               => "Th&%$ &%$ a test string"
 - Function File:  substr (S, BEG, LEN)
     Return the substring of S which starts at character number BEG and
     is LEN characters long.  For example,
          substr ("This is a test string", 6, 9)
               => "is a test"
          *Note:* This function is patterned after AWK.  You can get
          the same result by `S (BEG : (BEG + LEN - 1))'.
File: octave,  Node: String Conversions,  Next: Character Class Functions,  Prev: Searching and Replacing,  Up: Strings
String Conversions
==================
 - Function File:  bin2dec (S)
     Return a decimal number corresponding to the the binary number
     represented as a string of zeros and ones.  For example,
          bin2dec ("1110")
               => 14
 - Function File:  dec2bin (N)
     Return a binary number corresponding the the nonnegative decimal
     number N, as a string of ones and zeros.  For example,
          dec2bin (14)
               => "1110"
 - Function File:  dec2hex (N)
     Return the hexadecimal number corresponding to the nonnegative
     decimal number N, as a string.  For example,
          dec2hex (2748)
               => "abc"
 - Function File:  hex2dec (S)
     Return the decimal number corresponding to the hexadecimal number
     stored in the string S.  For example,
          hex2dec ("12B")
               => 299
          hex2dec ("12b")
               => 299
 - Function File:  str2num (S)
     Convert the string S to a number.
 - Function File:  toascii (S)
     Return ASCII representation of S in a matrix.  For example,
          toascii ("ASCII")
               => [ 65, 83, 67, 73, 73 ]
 - Function File:  tolower (S)
     Return a copy of the string S, with each upper-case character
     replaced by the corresponding lower-case one; nonalphabetic
     characters are left unchanged.  For example,
          tolower ("MiXeD cAsE 123")
               => "mixed case 123"
 - Function File:  toupper (S)
     Return a copy of the string S, with each  lower-case character
     replaced by the corresponding upper-case one; nonalphabetic
     characters are left unchanged.  For example,
          toupper ("MiXeD cAsE 123")
               => "MIXED CASE 123"
 - Built-in Function:  undo_string_escapes (S)
     Converts special characters in strings back to their escaped
     forms.  For example, the expression
          bell = "\a";
     assigns the value of the alert character (control-g, ASCII code 7)
     to the string variable `bell'.  If this string is printed, the
     system will ring the terminal bell (if it is possible).  This is
     normally the desired outcome.  However, sometimes it is useful to
     be able to print the original representation of the string, with
     the special characters replaced by their escape sequences.  For
     example,
          octave:13> undo_string_escapes (bell)
          ans = \a
     replaces the unprintable alert character with its printable
     representation.
 - Built-in Variable: implicit_str_to_num_ok
     If the value of `implicit_str_to_num_ok' is nonzero, implicit
     conversions of strings to their numeric ASCII equivalents are
     allowed.  Otherwise, an error message is printed and control is
     returned to the top level.  The default value is 0.
File: octave,  Node: Character Class Functions,  Prev: String Conversions,  Up: Strings
Character Class Functions
=========================
   Octave also provides the following character class test functions
patterned after the functions in the standard C library.  They all
operate on string arrays and return matrices of zeros and ones.
Elements that are nonzero indicate that the condition was true for the
corresponding character in the string array.  For example,
     isalpha ("!Q@WERT^Y&")
          => [ 0, 1, 0, 1, 1, 1, 1, 0, 1, 0 ]
 - Mapping Function:  isalnum (S)
     Return 1 for characters that are letters or digits (`isalpha (A)'
     or `isdigit ()' is true).
 - Mapping Function:  isalpha (S)
     Return true for characters that are letters (`isupper (A)' or
     `islower ()' is true).
 - Mapping Function:  isascii (S)
     Return 1 for characters that are ASCII (in the range 0 to 127
     decimal).
 - Mapping Function:  iscntrl (S)
     Return 1 for control characters.
 - Mapping Function:  isdigit (S)
     Return 1 for characters that are decimal digits.
 - Mapping Function:  isgraph (S)
     Return 1 for printable characters (but not the space character).
 - Mapping Function:  islower (S)
     Return 1 for characters that are lower case letters.
 - Mapping Function:  isprint (S)
     Return 1 for printable characters (including the space character).
 - Mapping Function:  ispunct (S)
     Return 1 for punctuation characters.
 - Mapping Function:  isspace (S)
     Return 1 for whitespace characters (space, formfeed, newline,
     carriage return, tab, and vertical tab).
 - Mapping Function:  isupper (S)
     Return 1 for upper case letters.
 - Mapping Function:  isxdigit (S)
     Return 1 for characters that are hexadecimal digits.